# UMD Plugin

import { SourceCode } from 'rspress/theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-umd" />

Used to build outputs in UMD format.

:::tip What is UMD
UMD stands for Universal Module Definition, which is a module specification that is compatible with AMD, CommonJS, and global variable definition. UMD outputs refer to modules that follow the UMD specification, allowing them to be loaded and used in different environments, including browser and Node.js.
:::

## Quick Start

### Install Plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-umd -D" />

### Register Plugin

You can register the plugin in the `rsbuild.config.ts` file:

```ts title="rsbuild.config.ts"
import { pluginUmd } from '@rsbuild/plugin-umd';

export default {
  plugins: [pluginUmd({ name: 'myLib' })],
};
```

## Example

For instance, the project contains the following code:

```js title="src/index.js"
export function double(a) {
  return a * 2;
}
```

When using the UMD plugin, Rsbuild will generate a `dist/index.js` file in UMD format.

- When loading this file in a browser, you can access the exported content through a global variable on the window object, for example:

```js
console.log(window.myLib.double(1)); // -> 2
```

- When loading in Node.js, you can import it directly using `require`, for example:

```js
const { double } = require('./dist/index.js');

console.log(double(1)); // -> 2
```

## Options

### name

`name` is a required field used to specify the name of the UMD library, corresponding to Rspack's [output.library.name](https://rspack.dev/config/output#outputlibraryname) option.

- **Type:** `string`
- **Example:**

```js
pluginUmd({
  name: 'foo', // accessed through window.foo
});
```

### export

Specifies which export to use as the content of the UMD library. By default, `export` is undefined, which exports the whole namespace object.

- **Type:** `string | string[]`
- **Default:** `undefined`
- **Example:** If `export` is configured as `default`, accessing `window.foo` will give you the content exported by `export default`.

```js
pluginUmd({
  name: 'foo',
  export: 'default',
});
```

- **Example 2:** You can also pass an array to `output.library.export`, and the array will be interpreted as an access path.

```js
pluginUmd({
  name: 'foo',
  export: ['default', 'subModule'],
});
```

```js title="src/index.js"
export default {
  // The value accessed through window.foo is 1
  subModule: 1,
};
```

## Output Filename

By default, the UMD plugin will output a `dist/index.js` file. You can modify the name of the output file through Rsbuild's [output.filename](/config/output/filename) option.

For example, output a `dist/myLib.js` file:

```js
export default {
  output: {
    filename: {
      js: 'myLib.js',
    },
  },
};
```

## Debugging in the Browser

You can run the `rsbuild dev` command to debug UMD outputs in the browser.

First, create `src/index.html` and add the following code:

```html title="src/index.html"
<!doctype html>
<html>
  <head></head>
  <body>
    <script>
      console.log(window.myLib.double(1));
    </script>
  </body>
</html>
```

Then, specify the `template` in `rsbuild.config.ts`:

```ts title="rsbuild.config.ts"
export default {
  plugins: [pluginUmd({ name: 'myLib' })],
  html: {
    template: './src/index.html',
  },
};
```

Finally, run `npx rsbuild dev` to start.

## HTML Generation

After using the UMD plugin, HTML files are not generated by default when running production builds. This is because UMD bundles are usually distributed as a library and do not rely on HTML files.

If you need to generate HTML files, you can set [tools.htmlPlugin](/config/tools/html-plugin) to `true`:

```ts title="rsbuild.config.ts"
export default {
  plugins: [pluginUmd({ name: 'myLib' })],
  html: {
    template: './src/index.html',
  },
  tools: {
    htmlPlugin: true,
  },
};
```

## Code Splitting

The UMD plugin overrides Rsbuild's default chunk splitting rules by setting `performance.chunkSplit.strategy` to `all-in-one` to output a single bundle. This is because UMD outputs are often distributed via CDN and allow direct referencing via `<script>` tags.

If you need to split the UMD outputs, you can actively configure [performance.chunkSplit](/config/performance/chunk-split), for example:

```js
export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-experience',
    },
  },
};
```

Note that the UMD plugin does not disable splits caused by dynamic imports. If you need to disable this, you can set the Rspack's [output.asyncChunks](https://rspack.dev/config/output#outputasyncchunks) option to `false`:

```js
export default {
  tools: {
    rspack: {
      output: {
        asyncChunks: false,
      },
    },
  },
};
```
